/**
 * 
 */
package com.googlecode.pcapj;

import java.io.File;
import java.io.IOException;

/**
 * Defines methods about capturing packets.
 */
public interface PacketCapture {
	/**
	 * Opens the PacketCapture object. 
	 * @throws IOException 
	 */
	public void open() throws IOException;
	/**
	 * Opens the PacketCapture object.
	 * @param snapLength length of the packet that has to be retained. 
	 * @param flags keeps several flags that can be needed for capturing packets. The allowed flags are defined in {@link OpenFlags} class.
	 * @param readTimeout read timeout in milliseconds. 
	 * @throws IOException
	 */
	public void open(int snapLength, int flags, int readTimeout) throws IOException;
	/**
	 * Collects a group of packets.<br>
	 * It keeps reading packets until {@link #breakLoop()} method is called or an error occurs.
	 * It does not return when live read timeouts occur.
	 * @param packetHandler
	 * @return true if breakLoop method is called.  
	 * @throws IOException
	 */
	public boolean loop(PacketHandler packetHandler) throws IOException;
	/**
	 * Read a captured object from an interface or from an off-line capture. 
	 * @return a captured object, or null if EOF was reached reading from an off-line capture.
	 * @throws PcapJTimeoutException
	 * @throws IOException
	 */
	public Captured read() throws PcapJTimeoutException, IOException;
	/**
	 * Set a flag that will force loop methods to return rather than looping. 
	 * @throws IOException
	 */
	public void breakLoop() throws IOException;
	/**
	 * Opens a dump file to write captured packet.
	 * @return the dump file.
	 */
	public DumpFileWriter openDumpFile(File file) throws IOException;
	/**
	 * Gets the data link layer type. 
	 * @return the value of the data link layer type. 
	 * @throws IOException
	 */
	public int getDataLinkLayerType() throws IOException;
	/**
	 * Closes the PacketCapture object.
	 * @throws IOException
	 */
	public void close() throws IOException;
	/**
	 * Returns whether the PacketCapture object is closed.
	 * @return true if the PacketCapture object is closed.
	 */
	public boolean isClosed();
}
